<li><p class="first">Integrated with a powerful validation system</p>
<blockquote>
<ul class="simple">
<li>including automatic type checking/conversion</li>
<li>repeated sections</li>
<li>and allowing default values</li>
</ul>
</blockquote>
</li>
<li><p class="first">When writing out config files, ConfigObj preserves all comments and the order of members and sections</p>
</li>
<li><p class="first">Many useful methods and options for working with configuration files (like the 'reload' method)</p>
</li>
<li><p class="first">Full Unicode support</p>
</li>
</ul>
<p>For support and bug reports please use the ConfigObj <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a>.</p>
<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py">configobj.py</a> from Voidspace</p>
<blockquote>
<p>ConfigObj has no external dependencies. This file is sufficient to access
all the functionality except <a class="reference internal" href="#validation">Validation</a>.</p>
</blockquote>
</li>
<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.5.3.zip">configobj.zip</a> from Voidspace</p>
<blockquote>
<p>This also contains <a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py">validate.py</a> and <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">this document</a>.</p>
</blockquote>
</li>
<li><p class="first">The latest development version can be obtained from the <a class="reference external" href="http://svn.pythonutils.python-hosting.com/trunk/pythonutils/">Subversion
Repository</a>.</p>
</li>
<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py">validate.py</a> from Voidspace</p>
</li>
<li><p class="first">You can also download <em>configobj.zip</em> from <a class="reference external" href="http://sourceforge.net/projects/configobj">Sourceforge</a></p>
<p>ConfigObj is also part of the <a class="reference external" href="http://www.voidspace.org.uk/python/pythonutils.html">Pythonutils</a> set of modules. This contains
various other useful modules, and is required by many of the <a class="reference external" href="http://www.voidspace.org.uk/python/index.shtml">Voidspace Python
Projects</a>.</p>
</div>
<div class="section" id="development-version">
<h2><a class="toc-backref" href="#id33">2.4 Development Version</a></h2>
<p>It is sometimes possible to get the latest <em>development version</em> of ConfigObj
from the <a class="reference external" href="http://svn.pythonutils.python-hosting.com/trunk/pythonutils/">Subversion Repository</a>.</p>
<p>Bazaar is a Python distributed <acronym title="Version Control System">VCS</acronym>.
ConfigObj is used to read <tt class="docutils literal"><span class="pre">bazaar.conf</span></tt> and <tt class="docutils literal"><span class="pre">branches.conf</span></tt>.</p>
<p>IPython is an enhanced interactive Python shell. IPython uses ConfigObj in a module called 'TConfig' that combines it with enthought <a class="reference external" href="http://code.enthought.com/traits/">Traits</a>: <a class="reference external" href="http://ipython.scipy.org/ipython/ipython/browser/ipython/branches/saw/sandbox/tconfig">tconfig</a>.</p>
</blockquote>
</li>
<li><p class="first"><a class="reference external" href="http://elisa.fluendo.com/">Elisa - the Fluendo Mediacenter</a></p>
<blockquote>
<p>Elisa is an open source cross-platform media center solution designed to be simple for people not particularly familiar with computers.</p>
<span class="pytext">config</span> <span class="pyoperator">=</span> <span class="pytext">ConfigObj</span><span class="pyoperator">(</span><span class="pytext">filename</span><span class="pyoperator">)</span><span class="pytext"></span></div><p>You can also pass the config file in as a list of lines, or a <tt class="docutils literal"><span class="pre">StringIO</span></tt>
instance, so it doesn't matter where your config data comes from.</p>
<p>You can then access members of your config file as a dictionary. Subsections
<p>You don't need to specify an infile. If you omit it, an empty ConfigObj will be
created. <tt class="docutils literal"><span class="pre">infile</span></tt> <em>can</em> be :</p>
<ul class="simple">
<li>Nothing. In which case the <tt class="docutils literal"><span class="pre">filename</span></tt> attribute of your ConfigObj will be
<tt class="docutils literal"><span class="pre">None</span></tt>. You can set a filename at any time.</li>
<li>A filename. What happens if the file doesn't already exist is determined by
the <a class="reference internal" href="#options">options</a> <tt class="docutils literal"><span class="pre">file_error</span></tt> and <tt class="docutils literal"><span class="pre">create_empty</span></tt>. The filename will be
preserved as the <tt class="docutils literal"><span class="pre">filename</span></tt> attribute. This can be changed at any time.</li>
<li>A list of lines. Any trailing newlines will be removed from the lines. The
<tt class="docutils literal"><span class="pre">filename</span></tt> attribute of your ConfigObj will be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li>A <tt class="docutils literal"><span class="pre">StringIO</span></tt> instance or file object, or any object with a <tt class="docutils literal"><span class="pre">read</span></tt> method.
The <tt class="docutils literal"><span class="pre">filename</span></tt> attribute of your ConfigObj will be <tt class="docutils literal"><span class="pre">None</span></tt> <a class="footnote-reference" href="#id20" id="id6">[5]</a>.</li>
<li>A dictionary. You can initialise a ConfigObj from a dictionary <a class="footnote-reference" href="#id21" id="id7">[6]</a>. The
<tt class="docutils literal"><span class="pre">filename</span></tt> attribute of your ConfigObj will be <tt class="docutils literal"><span class="pre">None</span></tt>. All keys must be
strings. In this case, the order of values and sections is arbitrary.</li>
<p>When parsing, it is possible that the config file will be badly formed. The
default is to parse the whole file and raise a single error at the end. You
can set <tt class="docutils literal"><span class="pre">raise_errors</span> <span class="pre">=</span> <span class="pre">True</span></tt> to have errors raised immediately. See the
<a class="reference internal" href="#exceptions">exceptions</a> section for more details.</p>
<p>Altering this value after initial parsing has no effect.</p>
<p>If <tt class="docutils literal"><span class="pre">True</span></tt> (the default) then list values are possible. If <tt class="docutils literal"><span class="pre">False</span></tt>, the
values are not parsed for lists.</p>
<blockquote>
<p>If <tt class="docutils literal"><span class="pre">list_values</span> <span class="pre">=</span> <span class="pre">False</span></tt> then single line values are not quoted or
unquoted when reading and writing.</p>
</blockquote>
<p>Changing this value affects whether single line values will be quoted or
<p>If this value is <tt class="docutils literal"><span class="pre">True</span></tt> and the file specified by <tt class="docutils literal"><span class="pre">infile</span></tt> doesn't
exist, ConfigObj will create an empty file. This can be a useful test that
the filename makes sense: an impossible filename will cause an error.</p>
<p>Altering this value after initial parsing has no effect.</p>
<p>If this value is <tt class="docutils literal"><span class="pre">True</span></tt> and the file specified by <tt class="docutils literal"><span class="pre">infile</span></tt> doesn't
exist, ConfigObj will raise an <tt class="docutils literal"><span class="pre">IOError</span></tt>.</p>
<p>Altering this value after initial parsing has no effect.</p>
<p>If you use the validation scheme, it can do type checking <em>and</em> conversion
for you. This means you may want to set members to integers, or other
non-string values.</p>
<p>If 'stringify' is set to <tt class="docutils literal"><span class="pre">True</span></tt> (default) then non-string values will
be converted to strings when you write the config file. The <a class="reference internal" href="#validation">validation</a>
process converts values from strings to the required type.</p>
<p>If 'stringify' is set to <tt class="docutils literal"><span class="pre">False</span></tt>, attempting to set a member to a
non-string value <a class="footnote-reference" href="#id22" id="id8">[7]</a> will raise a <tt class="docutils literal"><span class="pre">TypeError</span></tt> (no type conversion is
<p>When using the <tt class="docutils literal"><span class="pre">write</span></tt> method, <strong>ConfigObj</strong> uses the <tt class="docutils literal"><span class="pre">encoding</span></tt>
attribute to encode the Unicode strings. If any members (or keys) have
been set as byte strings instead of Unicode, these must first be decoded
to Unicode before outputting in the specified encoding.</p>
<p><tt class="docutils literal"><span class="pre">default_encoding</span></tt>, if specified, is the encoding used to decode byte
strings in the <strong>ConfigObj</strong> before writing. If this is <tt class="docutils literal"><span class="pre">None</span></tt>, then
the Python default encoding (<tt class="docutils literal"><span class="pre">sys.defaultencoding</span></tt> - usually ASCII) is
used.</p>
<p>For most Western European users, a value of <tt class="docutils literal"><span class="pre">latin-1</span></tt> is sensible.</p>
<p><tt class="docutils literal"><span class="pre">default_encoding</span></tt> is <em>only</em> used if an <tt class="docutils literal"><span class="pre">encoding</span></tt> is specified.</p>
<p>Any characters in byte-strings that can't be decoded using the
<tt class="docutils literal"><span class="pre">default_encoding</span></tt> will raise a <tt class="docutils literal"><span class="pre">UnicodeDecodeError</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">write_empty_values</span></tt> is <tt class="docutils literal"><span class="pre">True</span></tt>, empty strings are written as
empty values. See <a class="reference internal" href="#empty-values">Empty Values</a> for more details.</p>
<p>If you pass in a file like object to the <tt class="docutils literal"><span class="pre">write</span></tt> method, the config file will
be written to this. (The only method of this object that is used is its
<tt class="docutils literal"><span class="pre">write</span></tt> method, so a <tt class="docutils literal"><span class="pre">StringIO</span></tt> instance, or any other file like object
will work.)</p>
<p>Otherwise, the behaviour of this method depends on the <tt class="docutils literal"><span class="pre">filename</span></tt> attribute
<dd><tt class="docutils literal"><span class="pre">write</span></tt> returns a list of lines. (Not <tt class="docutils literal"><span class="pre">'\n'</span></tt> terminated)</dd>
</dl>
<p>First the 'initial_comment' is written, then the config file, followed by the
'final_comment'. Comment lines and inline comments are written with each
<span class="pykeyword">print</span> <span class="pystring">'Succeeded.'</span><span class="pytext"></span></div><p>The validate method uses the <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">validate</a> module to do the
validation.</p>
<p>This method validates the ConfigObj against the configspec. By doing type
conversion as well it can abstract away the config file altogether and present
the config <em>data</em> to your application (in the types it expects it to be).</p>
<p>If the <tt class="docutils literal"><span class="pre">configspec</span></tt> attribute of the ConfigObj is <tt class="docutils literal"><span class="pre">None</span></tt>, it raises a
<p>By default, the validate method either returns <tt class="docutils literal"><span class="pre">True</span></tt> (everything passed)
or a dictionary of <tt class="docutils literal"><span class="pre">True</span></tt>/<tt class="docutils literal"><span class="pre">False</span></tt> representing pass/fail. The dictionary
follows the structure of the ConfigObj.</p>
<p>If a whole section passes then it is replaced with the value <tt class="docutils literal"><span class="pre">True</span></tt>. If a
whole section fails, then it is replaced with the value <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>If a value is missing, and there is no default in the check, then the check
If you set this to <tt class="docutils literal"><span class="pre">True</span></tt>, instead of getting <tt class="docutils literal"><span class="pre">False</span></tt> for failed checks you
get the actual error object from the <strong>validate</strong> module. This usually contains
useful information about why the check failed.</p>
<p>See the <a class="reference internal" href="#flatten-errors">flatten_errors</a> function for how to turn your results dictionary into
a useful list of error messages.</p>
<p>Even if <tt class="docutils literal"><span class="pre">preserve_errors</span></tt> is <tt class="docutils literal"><span class="pre">True</span></tt>, missing keys or sections will still be
represented by a <tt class="docutils literal"><span class="pre">False</span></tt> in the results dictionary.</p>
<p>If the configspec check supplies a default and the value is missing in the
config, then the default will be set in your ConfigObj. (It is still passed to
the <tt class="docutils literal"><span class="pre">Validator</span></tt> so that type conversion can be done: this means the default
value must still pass the check.)</p>
<p>ConfigObj keeps a record of which values come from defaults, using the
<tt class="docutils literal"><span class="pre">defaults</span></tt> attribute of <a class="reference internal" href="#sections">sections</a>. Any key in this list isn't written out by
the <tt class="docutils literal"><span class="pre">write</span></tt> method. If a key is set from outside (even to the same value)
then it is removed from the <tt class="docutils literal"><span class="pre">defaults</span></tt> list.</p>
<!-- note:
Even if all the keys in a section are in the defaults list, the section
marker is still written out. -->
<p>There is additionally a special case default value of <tt class="docutils literal"><span class="pre">None</span></tt>. If you set the
default value to <tt class="docutils literal"><span class="pre">None</span></tt> and the value is missing, the value will always be
set to <tt class="docutils literal"><span class="pre">None</span></tt>. As the other checks don't return <tt class="docutils literal"><span class="pre">None</span></tt> (unless you
implement your own that do), you can tell that this value came from a default
value (and was missing from the config file). It allows an easy way of
implementing optional values. Simply check (and ignore) members that are set
to <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If <a class="reference internal" href="#stringify">stringify</a> is <tt class="docutils literal"><span class="pre">False</span></tt> then <tt class="docutils literal"><span class="pre">default=None</span></tt> returns <tt class="docutils literal"><span class="pre">''</span></tt> instead of
<tt class="docutils literal"><span class="pre">None</span></tt>. This is because setting a value to a non-string raises an error
if stringify is unset.</p>
</div>
<p>The default value can be a list. See <a class="reference internal" href="#id15">List Values</a> for the way to do this.</p>
<p>Writing invalid default values is a <em>guaranteed</em> way of confusing your users.
Default values <strong>must</strong> pass the check.</p>
<p>If a ConfigObj instance was loaded from the filesystem, then this method will reload it. It
will also reuse any configspec you supplied at instantiation (including reloading it from
the filesystem if you passed it in as a filename).</p>
<p>If the ConfigObj does not have a filename attribute pointing to a file, then a <tt class="docutils literal"><span class="pre">ReloadError</span></tt>
<p>ConfigObj can perform string interpolation in a <em>similar</em> way to
<tt class="docutils literal"><span class="pre">ConfigParser</span></tt>. See the <a class="reference internal" href="#string-interpolation">String Interpolation</a> section for full details.</p>
<p>If <tt class="docutils literal"><span class="pre">interpolation</span></tt> is set to <tt class="docutils literal"><span class="pre">False</span></tt>, then interpolation is <em>not</em> done when
<p>If this attribute is set (<tt class="docutils literal"><span class="pre">True</span></tt>) then the <a class="reference internal" href="#validate">validate</a> method changes the
values in the ConfigObj. These are turned back into strings when <a class="reference internal" href="#write">write</a> is
called.</p>
<p>If stringify is unset (<tt class="docutils literal"><span class="pre">False</span></tt>) then attempting to set a value to a non
string (or a list of strings) will raise a <tt class="docutils literal"><span class="pre">TypeError</span></tt>.</p>
<p>If the initial config file <em>started</em> with the UTF8 Unicode signature (known
slightly incorrectly as the <acronym title="Byte Order Mark">BOM</acronym>), or the UTF16 BOM, then
this attribute is set to <tt class="docutils literal"><span class="pre">True</span></tt>. Otherwise it is <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>If it is set to <tt class="docutils literal"><span class="pre">True</span></tt> when <tt class="docutils literal"><span class="pre">write</span></tt> is called then, if <tt class="docutils literal"><span class="pre">encoding</span></tt> is set
to <tt class="docutils literal"><span class="pre">None</span></tt> <em>or</em> to <tt class="docutils literal"><span class="pre">utf_8</span></tt> (and variants) a UTF BOM will be written.</p>
<p>For UTF16 encodings, a BOM is <em>always</em> written.</p>
<p>This attribute is <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>. If set to <tt class="docutils literal"><span class="pre">False</span></tt> then values are
not parsed for list values. In addition single line values are not unquoted.</p>
<p>This allows you to do your own parsing of values. It exists primarily to
support the reading of the <a class="reference internal" href="#configspec">configspec</a> - but has other use cases.</p>
<p>For example you could use the <tt class="docutils literal"><span class="pre">LineParser</span></tt> from the
<p>This is the encoding used to encode the output, when you call <tt class="docutils literal"><span class="pre">write</span></tt>. It
must be a valid encoding <a class="reference external" href="http://docs.python.org/lib/standard-encodings.html">recognised by Python</a>.</p>
<p>If this value is <tt class="docutils literal"><span class="pre">None</span></tt> then no encoding is done when <tt class="docutils literal"><span class="pre">write</span></tt> is called.</p>
<p>If encoding is set, any byte-strings in your ConfigObj instance (keys or
members) will first be decoded to Unicode using the encoding specified by the
<tt class="docutils literal"><span class="pre">default_encoding</span></tt> attribute. This ensures that the output is in the encoding
specified.</p>
<p>If this value is <tt class="docutils literal"><span class="pre">None</span></tt> then <tt class="docutils literal"><span class="pre">sys.defaultencoding</span></tt> is used instead.</p>
<p>When a config file is read, ConfigObj records the type of newline separators in the
file and uses this separator when writing. It defaults to <tt class="docutils literal"><span class="pre">None</span></tt>, and ConfigObj
uses the system default (<tt class="docutils literal"><span class="pre">os.sep</span></tt>) if write is called without newlines having
been set.</p>
</div>
</div>
</div>
<div class="section" id="the-config-file-format">
<h1><a class="toc-backref" href="#id64">6 The Config File Format</a></h1>
<p>You saw an example config file in the <a class="reference internal" href="#config-files">Config Files</a> section. Here is a fuller
specification of the config files used and created by ConfigObj.</p>
<p>The basic pattern for keywords is :</p>
<pre class="literal-block">
# comment line
# comment line
keyword = value # inline comment
</pre>
<p>Both keyword and value can optionally be surrounded in quotes. The equals sign
is the only valid divider.</p>
<p>Values can have comments on the lines above them, and an inline comment after
them. This, of course, is optional. See the <a class="reference internal" href="#comments">comments</a> section for details.</p>
<p>If a keyword or value starts or ends with whitespace, or contains a quote mark
or comma, then it should be surrounded by quotes. Quotes are not necessary if
whitespace is surrounded by non-whitespace.</p>
<p>Values can also be lists. Lists are comma separated. You indicate a single
member list by a trailing comma. An empty list is shown by a single comma :</p>
<pre class="literal-block">
keyword1 = value1, value2, value3
keyword2 = value1, # a single member list
keyword3 = , # an empty list
</pre>
<p>Values that contain line breaks (multi-line values) can be surrounded by triple
quotes. These can also be used if a value contains both types of quotes. List
members cannot be surrounded by triple quotes :</p>
<pre class="literal-block">
keyword1 = ''' A multi line value
on several
lines''' # with a comment
keyword2 = '''I won't be "afraid".'''
#
keyword3 = """ A multi line value
on several
lines""" # with a comment
keyword4 = """I won't be "afraid"."""
</pre>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">There is no way of safely quoting values that contain both types of triple
quotes.</p>
</div>
<p>A line that starts with a '#', possibly preceded by whitespace, is a comment.</p>
<p>New sections are indicated by a section marker line. That is the section name
in square brackets. Whitespace around the section name is ignored. The name can
be quoted with single or double quotes. The marker can have comments before it
and an inline comment after it :</p>
<pre class="literal-block">
# The First Section
[ section name 1 ] # first section
keyword1 = value1
# The Second Section
[ "section name 2" ] # second section
keyword2 = value2
</pre>
<p>Any subsections (sections that are <em>inside</em> the current section) are
designated by repeating the square brackets before and after the section name.
The number of square brackets represents the nesting level of the sub-section.
Square brackets may be separated by whitespace; such whitespace, however, will
not be present in the output config written by the <tt class="docutils literal"><span class="pre">write</span></tt> method.</p>
<p>Indentation is not significant, but can be preserved. See the description of
the <tt class="docutils literal"><span class="pre">indent_type</span></tt> option, in the <a class="reference internal" href="#configobj-specifications">ConfigObj specifications</a> chapter, for the
details.</p>
<p>A <em>NestingError</em> will be raised if the number of the opening and the closing
brackets in a section marker is not the same, or if a sub-section's nesting
level is greater than the nesting level of it parent plus one.</p>
<p>In the outer section, single values can only appear before any sub-section.
Otherwise they will belong to the sub-section immediately before them.</p>
<pre class="literal-block">
# initial comment
keyword1 = value1
keyword2 = value2
[section 1]
keyword1 = value1
keyword2 = value2
[[sub-section]]
# this is in section 1
keyword1 = value1
keyword2 = value2
[[[nested section]]]
# this is in sub section
keyword1 = value1
keyword2 = value2
[[sub-section2]]
# this is in section 1 again
keyword1 = value1
keyword2 = value2
[[sub-section3]]
# this is also in section 1, indentation is misleading here
keyword1 = value1
keyword2 = value2
# final comment
</pre>
<p>When parsed, the above config file produces the following data structure :</p>
<span class="pyoperator">}</span><span class="pyoperator">)</span><span class="pytext"></span></div><p>Sections are ordered: note how the structure of the resulting ConfigObj is in
the same order as the original file.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>In ConfigObj 4.3.0 <em>empty values</em> became valid syntax. They are read as the
empty string. There is also an option/attribute (<tt class="docutils literal"><span class="pre">write_empty_values</span></tt>) to
allow the writing of these.</p>
<p>This is mainly to support 'legacy' config files, written from other
applications. This is documented under <a class="reference internal" href="#empty-values">Empty Values</a>.</p>
<p class="last"><a class="reference internal" href="#unrepr-mode">unrepr mode</a> introduces <em>another</em> syntax variation, used for storing
<span class="pytext">False</span><span class="pytext"></span></div><p class="last">If you now change <tt class="docutils literal"><span class="pre">vals</span></tt>, the changes won't be reflected in <tt class="docutils literal"><span class="pre">config['vals']</span></tt>.</p>
</div>
<p>A section is ordered, following its <tt class="docutils literal"><span class="pre">scalars</span></tt> and <tt class="docutils literal"><span class="pre">sections</span></tt>
attributes documented below. This means that the following dictionary
attributes return their results in order.</p>
<ul>
<li><p class="first">'__iter__'</p>
<blockquote>
<p>More commonly known as <tt class="docutils literal"><span class="pre">for</span> <span class="pre">member</span> <span class="pre">in</span> <span class="pre">section:</span></tt>.</p>
</blockquote>
</li>
<li><p class="first">'__repr__' and '__str__'</p>
<blockquote>
<p>Any time you print or display the ConfigObj.</p>
<p>A reference to the 'parent' section, the section that this section is a
member of.</p>
<p>On the ConfigObj this attribute is a reference to itself. You can use this
to walk up the sections, stopping when <tt class="docutils literal"><span class="pre">section.parent</span> <span class="pre">is</span> <span class="pre">section</span></tt>.</p>
</blockquote>
</li>
<li><p class="first">depth</p>
<blockquote>
<p>The nesting level of the current section.</p>
<p>If you create a new ConfigObj and add sections, 1 will be added to the
depth level between sections.</p>
</blockquote>
</li>
<li><p class="first">defaults</p>
<blockquote>
<p>This attribute is a list of scalars that came from default values. Values
that came from defaults aren't written out by the <tt class="docutils literal"><span class="pre">write</span></tt> method.
Setting any of these values in the section removes them from the defaults
list.</p>
</blockquote>
</li>
<li><p class="first">default_values</p>
<blockquote>
<p>This attribute is a dictionary mapping keys to the default values for the
keys. By default it is an empty dictionary and is populated when you
validate the ConfigObj.</p>
</blockquote>
</li>
<li><p class="first">scalars, sections</p>
<blockquote>
<p>These attributes are normal lists, representing the order that members,
single values and subsections appear in the section. The order will either
be the order of the original config file, <em>or</em> the order that you added
members.</p>
<p>The order of members in this lists is the order that <tt class="docutils literal"><span class="pre">write</span></tt> creates in
the config file. The <tt class="docutils literal"><span class="pre">scalars</span></tt> list is output before the <tt class="docutils literal"><span class="pre">sections</span></tt>
list.</p>
<p>Adding or removing members also alters these lists. You can manipulate the
lists directly to alter the order of members.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you alter the <tt class="docutils literal"><span class="pre">scalars</span></tt>, <tt class="docutils literal"><span class="pre">sections</span></tt>, or <tt class="docutils literal"><span class="pre">defaults</span></tt> attributes
so that they no longer reflect the contents of the section, you will
break your ConfigObj.</p>
</div>
<p>See also the <tt class="docutils literal"><span class="pre">rename</span></tt> method.</p>
</blockquote>
</li>
<li><p class="first">comments</p>
<blockquote>
<p>This is a dictionary of comments associated with each member. Each entry is
a list of lines. These lines are written out before the member.</p>
</blockquote>
</li>
<li><p class="first">inline_comments</p>
<blockquote>
<p>This is <em>another</em> dictionary of comments associated with each member. Each
entry is a string that is put inline with the member.</p>
</blockquote>
</li>
<li><p class="first">configspec</p>
<blockquote>
<p>The configspec attribute is a dictionary mapping scalars to <em>checks</em>. A
check defines the expected type and possibly the allowed values for a
member.</p>
<p>The configspec has the same format as a config file, but instead of values
it has a specification for the value (which may include a default value).
The <a class="reference internal" href="#validate">validate</a> method uses it to check the config file makes sense. If a
configspec is passed in when the ConfigObj is created, then it is parsed
and broken up to become the <tt class="docutils literal"><span class="pre">configspec</span></tt> attribute of each section.</p>
<p>If you didn't pass in a configspec, this attribute will be <tt class="docutils literal"><span class="pre">None</span></tt> on the
root section (the main ConfigObj).</p>
<p>You can set the configspec attribute directly on a section.</p>
<p>See the <a class="reference internal" href="#validation">validation</a> section for full details of how to write configspecs.</p>
<p>This method renames a key, without affecting its position in the sequence.</p>
<p>It is mainly implemented for the <tt class="docutils literal"><span class="pre">encode</span></tt> and <tt class="docutils literal"><span class="pre">decode</span></tt> methods, which
<p>Returns <tt class="docutils literal"><span class="pre">True</span></tt> if the key contains a string that represents <tt class="docutils literal"><span class="pre">True</span></tt>, or
is the <tt class="docutils literal"><span class="pre">True</span></tt> object.</p>
<p>Returns <tt class="docutils literal"><span class="pre">False</span></tt> if the key contains a string that represents <tt class="docutils literal"><span class="pre">False</span></tt>,
or is the <tt class="docutils literal"><span class="pre">False</span></tt> object.</p>
<p>Raises a <tt class="docutils literal"><span class="pre">ValueError</span></tt> if the key contains anything else.</p>
<p>Strings that represent <tt class="docutils literal"><span class="pre">True</span></tt> are (not case sensitive) :</p>
<pre class="literal-block">
true, yes, on, 1
</pre>
<p>Strings that represent <tt class="docutils literal"><span class="pre">False</span></tt> are :</p>
<pre class="literal-block">
false, no, off, 0
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">In ConfigObj 4.1.0, this method was called <tt class="docutils literal"><span class="pre">istrue</span></tt>. That method is
now deprecated and will issue a warning when used. It will go away
<span class="pytext">call_on_sections</span><span class="pyoperator">=</span><span class="pytext">False</span><span class="pyoperator">,</span> <span class="pyoperator">**</span><span class="pytext">keywargs</span><span class="pyoperator">)</span><span class="pyoperator">:</span><span class="pytext"></span></div><p><tt class="docutils literal"><span class="pre">walk</span></tt> is a method of the <tt class="docutils literal"><span class="pre">Section</span></tt> object. This means it is also a method
of ConfigObj.</p>
<p>It walks through every member and calls a function on the keyword and value. It
walks recursively through subsections.</p>
<p>It returns a dictionary of all the computed values.</p>
<p>If the function raises an exception, the default is to propagate the error, and
stop. If <tt class="docutils literal"><span class="pre">raise_errors=False</span></tt> then it sets the return value for that keyword
to <tt class="docutils literal"><span class="pre">False</span></tt> instead, and continues. This is similar to the way <a class="reference internal" href="#validation">validation</a>
works.</p>
<p>Your function receives the arguments <tt class="docutils literal"><span class="pre">(section,</span> <span class="pre">key)</span></tt>. The current value is
then <tt class="docutils literal"><span class="pre">section[key]</span></tt> <a class="footnote-reference" href="#id26" id="id12">[11]</a>. Any unrecognised keyword arguments you pass to
walk, are passed on to the function.</p>
<p>Normally <tt class="docutils literal"><span class="pre">walk</span></tt> just recurses into subsections. If you are transforming (or
checking) names as well as values, then you want to be able to change the names
of sections. In this case set <tt class="docutils literal"><span class="pre">call_on_sections</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt>. Now, on
encountering a sub-section, <em>first</em> the function is called for the <em>whole</em>
sub-section, and <em>then</em> it recurses into it's members. This means your function
must be able to handle receiving dictionaries as well as strings and lists.</p>
<p>If you are using the return value from <tt class="docutils literal"><span class="pre">walk</span></tt> <em>and</em> <tt class="docutils literal"><span class="pre">call_on_sections</span></tt>,
note that walk discards the return value when it calls your function.</p>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p class="last">You can use <tt class="docutils literal"><span class="pre">walk</span></tt> to transform the names of members of a section
<p>Examples that use the walk method are the <tt class="docutils literal"><span class="pre">encode</span></tt> and <tt class="docutils literal"><span class="pre">decode</span></tt> methods.
They both define a function and pass it to walk. Because these functions
transform names as well as values (from byte strings to Unicode) they set
<p>To see how they do it, <em>read the source Luke</em> <img src="/smilies/cool.gif" alt="Cool" height="15" width="15" /> .</p>
<p>You can use this for transforming all values in your ConfigObj. For example
you might like the nested lists from ConfigObj 3. This was provided by the
<a class="reference external" href="http://www.voidspace.org.uk/python/modules.shtml#listquote">listquote</a> module. You could switch off the parsing for list values
(<tt class="docutils literal"><span class="pre">list_values=False</span></tt>) and use listquote to parse every value.</p>
<p>Another thing you might want to do is use the Python escape codes in your
values. You might be <em>used</em> to using <tt class="docutils literal"><span class="pre">\n</span></tt> for line feed and <tt class="docutils literal"><span class="pre">\t</span></tt> for tab.
Obviously we'd need to decode strings that come from the config file (using the
escape codes). Before writing out we'll need to put the escape codes back in
encode.</p>
<p>As an example we'll write a function to use with walk, that encodes or decodes
values using the <tt class="docutils literal"><span class="pre">string-escape</span></tt> codec.</p>
<p>The function has to take each value and set the new value. As a bonus we'll
create one function that will do decode <em>or</em> encode depending on a keyword
argument.</p>
<p>We don't want to work with section names, we're only transforming values, so
we can leave <tt class="docutils literal"><span class="pre">call_on_sections</span></tt> as <tt class="docutils literal"><span class="pre">False</span></tt>. This means the two datatypes we
have to handle are strings and lists, we can ignore everything else. (We'll
treat tuples as lists as well).</p>
<p>We're not using the return values, so it doesn't need to return anything, just
</span><span class="pycomment"># Because ``walk`` doesn't recognise the ``encode`` argument<br />
</span><span class="pycomment"># it passes it to our function.<br />
</span><span class="pytext">config</span><span class="pyoperator">.</span><span class="pytext">walk</span><span class="pyoperator">(</span><span class="pytext">string_escape</span><span class="pyoperator">,</span> <span class="pytext">encode</span><span class="pyoperator">=</span><span class="pytext">True</span><span class="pyoperator">)</span><span class="pytext"></span></div><p>Here's a simple example of using <tt class="docutils literal"><span class="pre">walk</span></tt> to transform names and values. One
usecase of this would be to create a <em>standard</em> config file with placeholders
for section and keynames. You can then use walk to create new config files
and change values and member names :</p>
<div class="pysrc"><span class="pycomment"># We use 'XXXX' as a placeholder<br />
<p>There are several places where ConfigObj may raise exceptions (other than
because of bugs).</p>
<ol class="arabic">
<li><dl class="first docutils">
<dt>If a configspec filename you pass in doesn't exist, or a config file</dt>
<dd><p class="first last">filename doesn't exist <em>and</em> <tt class="docutils literal"><span class="pre">file_error=True</span></tt>, an <tt class="docutils literal"><span class="pre">IOError</span></tt> will be
raised.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>If you try to set a non-string key, or a non string value when</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">stringify=False</span></tt>, a <tt class="docutils literal"><span class="pre">TypeError</span></tt> will be raised.</p>
</dd>
</dl>
</li>
<li><p class="first">A badly built config file will cause parsing errors.</p>
</li>
<li><p class="first">A parsing error can also occur when reading a configspec.</p>
</li>
<li><dl class="first docutils">
<dt>In string interpolation you can specify a value that doesn't exist, or</dt>
<p>Number 6 is explained in the <a class="reference internal" href="#validation">validation</a> section.</p>
<p><em>This</em> section is about errors raised during parsing.</p>
<p>The base error class is <tt class="docutils literal"><span class="pre">ConfigObjError</span></tt>. This is a subclass of
<tt class="docutils literal"><span class="pre">SyntaxError</span></tt>, so you can trap for <tt class="docutils literal"><span class="pre">SyntaxError</span></tt> without needing to
directly import any of the ConfigObj exceptions.</p>
<p>The following other exceptions are defined (all deriving from
<p>This error indicates that a line is badly written. It is neither a valid
<tt class="docutils literal"><span class="pre">key</span> <span class="pre">=</span> <span class="pre">value</span></tt> line, nor a valid section marker line, nor a comment line.</p>
<p><tt class="docutils literal"><span class="pre">reload</span></tt> was called on a ConfigObj instance that doesn't have a valid
filename attribute.</p>
</blockquote>
</li>
</ul>
<p>When parsing a configspec, ConfigObj will stop on the first error it
encounters. It will raise a <tt class="docutils literal"><span class="pre">ConfigspecError</span></tt>. This will have an <tt class="docutils literal"><span class="pre">error</span></tt>
attribute, which is the actual error that was raised.</p>
<p>Behaviour when parsing a config file depends on the option <tt class="docutils literal"><span class="pre">raise_errors</span></tt>.
If ConfigObj encounters an error while parsing a config file:</p>
<blockquote>
<p>If <tt class="docutils literal"><span class="pre">raise_errors=True</span></tt> then ConfigObj will raise the appropriate error
and parsing will stop.</p>
<p>If <tt class="docutils literal"><span class="pre">raise_errors=False</span></tt> (the default) then parsing will continue to the
end and <em>all</em> errors will be collected.</p>
</blockquote>
<p>If <tt class="docutils literal"><span class="pre">raise_errors</span></tt> is False and multiple errors are found a <tt class="docutils literal"><span class="pre">ConfigObjError</span></tt>
is raised. The error raised has a <tt class="docutils literal"><span class="pre">config</span></tt> attribute, which is the parts of
the ConfigObj that parsed successfully. It also has an attribute <tt class="docutils literal"><span class="pre">errors</span></tt>,
which is a list of <em>all</em> the errors raised. Each entry in the list is an
instance of the appropriate error type. Each one has the following attributes
(useful for delivering a sensible error message to your user) :</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">line</span></tt>: the original line that caused the error.</li>
<li><tt class="docutils literal"><span class="pre">line_number</span></tt>: its number in the config file.</li>
<li><tt class="docutils literal"><span class="pre">message</span></tt>: the error message that accompanied the error.</li>
</ul>
<p>If only one error is found, then that error is re-raised. The error still has
the <tt class="docutils literal"><span class="pre">config</span></tt> and <tt class="docutils literal"><span class="pre">errors</span></tt> attributes. This means that your error handling
code can be the same whether one error is raised in parsing , or several.</p>
<p>It also means that in the most common case (a single error) a useful error
message will be raised.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">One wrongly written line could break the basic structure of your config
file. This could cause every line after it to flag an error, so having a
list of all the lines that caused errors may not be as useful as it sounds.
<p class="last">The system of configspecs can seem confusing at first, but is actually
quite simple and powerful. For a concrete example of how to use it, you may
find this blog entry helpful :
<a class="reference external" href="http://www.voidspace.org.uk/python/weblog/arch_d7_2006_03_04.shtml#e257">Transforming Values with ConfigObj</a>.</p>
</div>
<p>Validation is done through a combination of the <a class="reference internal" href="#configspec">configspec</a> and a <tt class="docutils literal"><span class="pre">Validator</span></tt>
object. For this you need <em>validate.py</em> <a class="footnote-reference" href="#id27" id="id14">[12]</a>. See <a class="reference internal" href="#downloading">downloading</a> if you don't
have a copy.</p>
<p>Validation can perform two different operations :</p>
<ol class="arabic">
<li><dl class="first docutils">
<dt>Check that a value meets a specification. For example, check that a value</dt>
<dd><p class="first last">is an integer between one and six, or is a choice from a specific set of
options.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>It can convert the value into the type required. For example, if one of</dt>
<dd><p class="first last">your values is a port number, validation will turn it into an integer for
you.</p>
</dd>
</dl>
</li>
</ol>
<p>So validation can act as a transparent layer between the datatypes of your
application configuration (boolean, integers, floats, etc) and the text format
<p>The <tt class="docutils literal"><span class="pre">validate</span></tt> method checks members against an entry in the configspec. Your
configspec therefore resembles your config file, with a check for every member.</p>
<p>In order to perform validation you need a <tt class="docutils literal"><span class="pre">Validator</span></tt> object. This has
several useful built-in check functions. You can also create your own custom
functions and register them with your Validator object.</p>
<p>Each check is the name of one of these functions, including any parameters and
keyword arguments. The configspecs look like function calls, and they map to
function calls.</p>
<p>The basic datatypes that an un-extended Validator can test for are :</p>
<ul class="simple">
<li>boolean values (True and False)</li>
<li>integers (including minimum and maximum values)</li>
<li>floats (including min and max)</li>
<li>strings (including min and max length)</li>
<li>IP addresses (v4 only)</li>
</ul>
<p>It can also handle lists of these types and restrict a value to being one from
a set of options.</p>
<p>An example configspec is going to look something like :</p>
<pre class="literal-block">
port = integer(0, 100)
user = string(max=25)
mode = option('quiet', 'loud', 'silent')
</pre>
<p>You can specify default values, and also have the same configspec applied to
several sections. This is called <a class="reference internal" href="#repeated-sections">repeated sections</a>.</p>
<p>For full details on writing configspecs, please refer to the <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">validate.py
documentation</a>.</p>
<div class="important">
<p class="first admonition-title">Important</p>
<p>Your configspec is read by ConfigObj in the same way as a config file.</p>
<p>That means you can do interpolation <em>within</em> your configspec.</p>
<p class="last">In order to allow this, checks in the 'DEFAULT' section (of the root level
of your configspec) are <em>not</em> used.</p>
</div>
<p>If you need to specify the encoding of your configspec, then you can pass in a
ConfigObj instance as your configspec. When you read your configspec file, you
<h2><a class="toc-backref" href="#id73">9.2 Type Conversion</a></h2>
<p>By default, validation does type conversion. This means that if you specify
<tt class="docutils literal"><span class="pre">integer</span></tt> as the check, then calling <a class="reference internal" href="#validate">validate</a> will actually change the value
to an integer (so long as the check succeeds).</p>
<p>It also means that when you call the <a class="reference internal" href="#write">write</a> method, the value will be converted
back into a string using the <tt class="docutils literal"><span class="pre">str</span></tt> function.</p>
<p>To switch this off, and leave values as strings after validation, you need to
set the <a class="reference internal" href="#stringify">stringify</a> attribute to <tt class="docutils literal"><span class="pre">False</span></tt>. If this is the case, attempting to
set a value to a non-string will raise an error.</p>
<p>You can set a default value in your check. If the value is missing from the
config file then this value will be used instead. This means that your user
only has to supply values that differ from the defaults.</p>
<p>If you <em>don't</em> supply a default then for a value to be missing is an error,
and this will show in the <a class="reference internal" href="#return-value">return value</a> from validate.</p>
<p>Additionally you can set the default to be <tt class="docutils literal"><span class="pre">None</span></tt>. This means the value will
be set to <tt class="docutils literal"><span class="pre">None</span></tt> (the object) <em>whichever check is used</em>. (It will be set to
<tt class="docutils literal"><span class="pre">''</span></tt> rather than <tt class="docutils literal"><span class="pre">None</span></tt> if <a class="reference internal" href="#stringify">stringify</a> is <tt class="docutils literal"><span class="pre">False</span></tt>). You can use this
to easily implement optional values in your config files.</p>
<p>Repeated sections are a way of specifying a configspec for a section that
should be applied to <em>all</em> subsections in the same section.</p>
<p>The easiest way of explaining this is to give an example. Suppose you have a
config file that describes a dog. That dog has various attributes, but it can
also have many fleas. You don't know in advance how many fleas there will be,
or what they will be called, but you want each flea validated against the same
configspec.</p>
<p>We can define a section called <em>fleas</em>. We want every flea in that section
(every sub-section) to have the same configspec applied to it. We do this by
defining a single section called <tt class="docutils literal"><span class="pre">__many__</span></tt>.</p>
<pre class="literal-block">
[dog]
name = string(default=Rover)
age = float(0, 99, default=0)
[[fleas]]
[[[__many__]]]
bloodsucker = boolean(default=True)
children = integer(default=10000)
size = option(small, tiny, micro, default=tiny)
</pre>
<p>Every flea on our dog will now be validated using the <tt class="docutils literal"><span class="pre">__many__</span></tt> configspec.</p>
<p>If you define another sub-section in a section <em>as well as</em> a <tt class="docutils literal"><span class="pre">__many__</span></tt> then
you will get an error.</p>
<p><tt class="docutils literal"><span class="pre">__many__</span></tt> sections can have sub-sections, including their own <tt class="docutils literal"><span class="pre">__many__</span></tt>
sub-sections. Defaults work in the normal way in repeated sections.</p>
<p>You may not need a full validation process, but still want to check if all the
expected values are present.</p>
<p>Provided as part of the ConfigObj module is the <tt class="docutils literal"><span class="pre">SimpleVal</span></tt> object. This has
a dummy <tt class="docutils literal"><span class="pre">test</span></tt> method that always passes.</p>
<p>The only reason a test will fail is if the value is missing. The return value
from <tt class="docutils literal"><span class="pre">validate</span></tt> will either be <tt class="docutils literal"><span class="pre">True</span></tt>, meaning all present, or a dictionary
with <tt class="docutils literal"><span class="pre">False</span></tt> for all missing values/sections.</p>
<p>To use it, you still need to pass in a valid configspec when you create the
ConfigObj, but just set all the values to <tt class="docutils literal"><span class="pre">''</span></tt>. Then create an instance of
<tt class="docutils literal"><span class="pre">SimpleVal</span></tt> and pass it to the <tt class="docutils literal"><span class="pre">validate</span></tt> method.</p>
<p>As a trivial example if you had the following config file :</p>
<p>You can't store classes, types or instances.</p>
<p><tt class="docutils literal"><span class="pre">unrepr</span></tt> uses <tt class="docutils literal"><span class="pre">repr(object)</span></tt> to write out values, so it currently <em>doesn't</em>
check that you are writing valid objects. If you attempt to read an unsupported
value, ConfigObj will raise a <tt class="docutils literal"><span class="pre">configobj.UnknownType</span></tt> exception.</p>
<p>Values that are triple quoted cased. The triple quotes are removed <em>before</em>
converting. This means that you can use triple quotes to write dictionaries
over several lines in your config files. They won't be written like this
though.</p>
<p>If you are writing config files by hand, for use with <tt class="docutils literal"><span class="pre">unrepr</span></tt>, you should
be aware of the following differences from normal ConfigObj syntax :</p>
<p>ConfigObj allows string interpolation <em>similar</em> to the way <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>
or <tt class="docutils literal"><span class="pre">string.Template</span></tt> work. The value of the <tt class="docutils literal"><span class="pre">interpolation</span></tt> attribute
determines which style of interpolation you want to use. Valid values are
"ConfigParser" or "Template" (case-insensitive, so "configparser" and
"template" will also work). For backwards compatibility reasons, the value
<tt class="docutils literal"><span class="pre">True</span></tt> is also a valid value for the <tt class="docutils literal"><span class="pre">interpolation</span></tt> attribute, and
will select <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>-style interpolation. At some undetermined point
in the future, that default <em>may</em> change to <tt class="docutils literal"><span class="pre">Template</span></tt>-style interpolation.</p>
<p>For <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>-style interpolation, you specify a value to be
substituted by including <tt class="docutils literal"><span class="pre">%(name)s</span></tt> in the value.</p>
<p>For <tt class="docutils literal"><span class="pre">Template</span></tt>-style interpolation, you specify a value to be substituted
by including <tt class="docutils literal"><span class="pre">${name}</span></tt> in the value. Alternately, if 'name' is a valid
Python identifier (i.e., is composed of nothing but alphanumeric characters,
plus the underscore character), then the braces are optional and the value
can be written as <tt class="docutils literal"><span class="pre">$name</span></tt>.</p>
<p>Note that <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>-style interpolation and <tt class="docutils literal"><span class="pre">Template</span></tt>-style
interpolation are mutually exclusive; you cannot have a configuration file
that's a mix of one or the other. Pick one and stick to it. <tt class="docutils literal"><span class="pre">Template</span></tt>-style
interpolation is simpler to read and write by hand, and is recommended if
you don't have a particular reason to use <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>-style.</p>
<p>Interpolation checks first the current section to see if <tt class="docutils literal"><span class="pre">name</span></tt> is the key
to a value. ('name' is case sensitive).</p>
<p>If it doesn't find it, next it checks the 'DEFAULT' sub-section of the current
section.</p>
<p>If it still doesn't find it, it moves on to check the parent section and the
parent section's 'DEFAULT' subsection, and so on all the way up to the main
section.</p>
<p>If the value specified isn't found in any of these locations, then a
<tt class="docutils literal"><span class="pre">MissingInterpolationOption</span></tt> error is raised (a subclass of
<p><a class="reference internal" href="#validation">Validation</a> is a powerful way of checking that the values supplied by the user
make sense.</p>
<p>The <a class="reference internal" href="#validate">validate</a> method returns a results dictionary that represents pass or fail
for each value. This doesn't give you any information about <em>why</em> the check
failed.</p>
<p><tt class="docutils literal"><span class="pre">flatten_errors</span></tt> is an example function that turns a results dictionary into
a flat list, that only contains values that <em>failed</em>.</p>
<p><tt class="docutils literal"><span class="pre">cfg</span></tt> is the ConfigObj instance being checked, <tt class="docutils literal"><span class="pre">res</span></tt> is the results
dictionary returned by <tt class="docutils literal"><span class="pre">validate</span></tt>.</p>
<p>It returns a list of keys that failed. Each member of the list is a tuple :</p>
<pre class="literal-block">
([list of sections...], key, result)
</pre>
<p>If <tt class="docutils literal"><span class="pre">validate</span></tt> was called with <tt class="docutils literal"><span class="pre">preserve_errors=False</span></tt> (the default)
then <tt class="docutils literal"><span class="pre">result</span></tt> will always be <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p><em>list of sections</em> is a flattened list of sections that the key was found
in.</p>
<p>If the section was missing then key will be <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<p>If the value (or section) was missing then <tt class="docutils literal"><span class="pre">result</span></tt> will be <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">validate</span></tt> was called with <tt class="docutils literal"><span class="pre">preserve_errors=True</span></tt> and a value
was present, but failed the check, then <tt class="docutils literal"><span class="pre">result</span></tt> will be the exception
object returned. You can use this as a string that describes the failure.</p>
<p>For example :</p>
<blockquote>
<em>The value "3" is of the wrong type</em>.</blockquote>
<div class="section" id="example-usage">
<h2><a class="toc-backref" href="#id85">14.1 Example Usage</a></h2>
<p>The output from <tt class="docutils literal"><span class="pre">flatten_errors</span></tt> is a list of tuples.</p>
<p>Here is an example of how you could present this information to the user.</p>
<p>ConfigObj 3 is now deprecated in favour of ConfigObj 4. I can fix bugs in
ConfigObj 3 if needed, though.</p>
<p>For anyone who still needs it, you can download it here: <a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj3.zip">ConfigObj 3.3.1</a></p>
<p>You can read the old docs at : <a class="reference external" href="http://www.voidspace.org.uk/python/configobj3.html">ConfigObj 3 Docs</a></p>
<p>ConfigObj 4 is written by (and copyright) <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a> and
Copyright (c) 2004 - 2008, Michael Foord & Nicola Larosa
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
* Neither the name of Michael Foord nor Nicola Larosa
may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
<p>You should also be able to find a copy of this license at : <a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></p>
<p class="last">Please file any bug reports to <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a> or the <strong>ConfigObj</strong>
<h2><a class="toc-backref" href="#id93">20.2 2008/02/05 - Version 4.5.2</a></h2>
<p>Distribution updated to include version 0.3.2 of <a class="reference internal" href="#validate">validate</a>. This means that
<tt class="docutils literal"><span class="pre">None</span></tt> as a default value win configspecs works.</p>
</div>
<div class="section" id="version-4-5-1">
<h2><a class="toc-backref" href="#id94">20.3 2008/02/05 - Version 4.5.1</a></h2>
<p>Distribution updated to include version 0.3.1 of <a class="reference internal" href="#validate">validate</a>. This means that
Unicode configspecs now work.</p>
</div>
<div class="section" id="version-4-5-0">
<h2><a class="toc-backref" href="#id95">20.4 2008/02/05 - Version 4.5.0</a></h2>
<p>ConfigObj will now guarantee that files will be written terminated with a
newline.</p>
<p>ConfigObj will no longer attempt to import the <tt class="docutils literal"><span class="pre">validate</span></tt> module, until/unless
you call <tt class="docutils literal"><span class="pre">ConfigObj.validate</span></tt> with <tt class="docutils literal"><span class="pre">preserve_errors=True</span></tt>. This makes it
resets an entry to its default value (and returns that value). <tt class="docutils literal"><span class="pre">restore_defaults</span></tt>
resets all entries to their default value. It doesn't modify entries without a
default value. You must have validated a ConfigObj (which populates the
<tt class="docutils literal"><span class="pre">default_values</span></tt> dictionary) before calling these methods.</p>
<p>BUGFIX: Proper quoting of keys, values and list values that contain hashes
(when writing). When <tt class="docutils literal"><span class="pre">list_values=False</span></tt>, values containing hashes are
triple quoted.</p>
<p>Added the <tt class="docutils literal"><span class="pre">reload</span></tt> method. This reloads a ConfigObj from file. If the filename
attribute is not set then a <tt class="docutils literal"><span class="pre">ReloadError</span></tt> (a new exception inheriting from
<tt class="docutils literal"><span class="pre">IOError</span></tt>) is raised.</p>
<p>BUGFIX: Files are read in with 'rb' mode, so that native/non-native line endings work!</p>
<p>Minor efficiency improvement in <tt class="docutils literal"><span class="pre">unrepr</span></tt> mode.</p>
<p>Added missing docstrings for some overidden dictionary methods.</p>
<p>Added the <tt class="docutils literal"><span class="pre">reset</span></tt> method. This restores a ConfigObj to a freshly created state.</p>
<p>Removed old CHANGELOG file.</p>
</div>
<div class="section" id="version-4-4-0">
<h2><a class="toc-backref" href="#id96">20.5 2007/02/04 - Version 4.4.0</a></h2>
<p>Official release of 4.4.0</p>
</div>
<div class="section" id="version-4-3-3-alpha4">
<h2><a class="toc-backref" href="#id97">20.6 2006/12/17 - Version 4.3.3-alpha4</a></h2>
<p>By Nicola Larosa</p>
<p>Allowed arbitrary indentation in the <tt class="docutils literal"><span class="pre">indent_type</span></tt> parameter, removed the
<tt class="docutils literal"><span class="pre">NUM_INDENT_SPACES</span></tt> and <tt class="docutils literal"><span class="pre">MAX_INTERPOL_DEPTH</span></tt> (a leftover) constants,
added indentation tests (including another docutils workaround, sigh), updated
the documentation.</p>
<p>By Michael Foord</p>
<p>Made the import of <tt class="docutils literal"><span class="pre">compiler</span></tt> conditional so that <tt class="docutils literal"><span class="pre">ConfigObj</span></tt> can be used
with <a class="reference external" href="http://www.codeplex.com/IronPython">IronPython</a>.</p>
</div>
<div class="section" id="version-4-3-3-alpha3">
<h2><a class="toc-backref" href="#id98">20.7 2006/12/17 - Version 4.3.3-alpha3</a></h2>
<p>By Nicola Larosa</p>
<p>Added a missing <tt class="docutils literal"><span class="pre">self.</span></tt> in the _handle_comment method and a related test,
per Sourceforge bug #1523975.</p>
</div>
<div class="section" id="version-4-3-3-alpha2">
<h2><a class="toc-backref" href="#id99">20.8 2006/12/09 - Version 4.3.3-alpha2</a></h2>
<p>By Nicola Larosa</p>
<p>Changed interpolation search strategy, based on this patch by Robin Munn:
<h2><a class="toc-backref" href="#id100">20.9 2006/12/09 - Version 4.3.3-alpha1</a></h2>
<p>By Nicola Larosa</p>
<p>Added Template-style interpolation, with tests, based on this patch by
Robin Munn: <a class="reference external" href="http://sourceforge.net/mailarchive/message.php?msg_id=17125991">http://sourceforge.net/mailarchive/message.php?msg_id=17125991</a>
(awful archives, bad Sourceforge, bad).</p>
</div>
<div class="section" id="version-4-3-2">
<h2><a class="toc-backref" href="#id101">20.10 2006/06/04 - Version 4.3.2</a></h2>
<p>Changed error handling, if parsing finds a single error then that error will
be re-raised. That error will still have an <tt class="docutils literal"><span class="pre">errors</span></tt> and a <tt class="docutils literal"><span class="pre">config</span></tt>
attribute.</p>
<p>Fixed bug where '\n' terminated files could be truncated.</p>
<p>Bugfix in <tt class="docutils literal"><span class="pre">unrepr</span></tt> mode, it couldn't handle '#' in values. (Thanks to
Philippe Normand for the report.)</p>
<p>As a consequence of this fix, ConfigObj doesn't now keep inline comments in
<tt class="docutils literal"><span class="pre">unrepr</span></tt> mode. This is because the parser in the <a class="reference external" href="http://docs.python.org/lib/compiler.html">compiler package</a>
<p>Error messages are now more useful. They tell you the number of parsing errors
and the line number of the first error. (In the case of multiple errors.)</p>
<p>Line numbers in exceptions now start at 1, not 0.</p>
<p>Errors in <tt class="docutils literal"><span class="pre">unrepr</span></tt> mode are now handled the same way as in the normal mode.
The errors stored will be an <tt class="docutils literal"><span class="pre">UnreprError</span></tt>.</p>
</div>
<div class="section" id="version-4-3-1">
<h2><a class="toc-backref" href="#id102">20.11 2006/04/29 - Version 4.3.1</a></h2>
<p>Added <tt class="docutils literal"><span class="pre">validate.py</span></tt> back into <tt class="docutils literal"><span class="pre">configobj.zip</span></tt>. (Thanks to Stewart
Midwinter)</p>
<p>Updated to <a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py">validate.py</a> 0.2.2.</p>
<p>Preserve tuples when calling the <tt class="docutils literal"><span class="pre">dict</span></tt> method. (Thanks to Gustavo Niemeyer.)</p>
<p>Changed <tt class="docutils literal"><span class="pre">__repr__</span></tt> to return a string that contains <tt class="docutils literal"><span class="pre">ConfigObj({</span> <span class="pre">...</span> <span class="pre">})</span></tt>.</p>
<p>Change so that an options dictionary isn't modified by passing it to ConfigObj.
(Thanks to Artarious.)</p>
<p>Added ability to handle negative integers in <tt class="docutils literal"><span class="pre">unrepr</span></tt>. (Thanks to Kevin
Dangoor.)</p>
</div>
<div class="section" id="version-4-3-0">
<h2><a class="toc-backref" href="#id103">20.12 2006/03/24 - Version 4.3.0</a></h2>
<p>Moved the tests and the CHANGELOG (etc) into a separate file. This has reduced
the size of <tt class="docutils literal"><span class="pre">configobj.py</span></tt> by about 40%.</p>
<p>Added the <tt class="docutils literal"><span class="pre">unrepr</span></tt> mode to reading and writing config files. Thanks to Kevin
Dangoor for this suggestion.</p>
<p>Empty values are now valid syntax. They are read as an empty string <tt class="docutils literal"><span class="pre">''</span></tt>.
<p>You can now pass in a ConfigObj instance as a configspec (remember to read
the configspec file using <tt class="docutils literal"><span class="pre">list_values=False</span></tt>).</p>
<p>Sorted footnotes in the docs.</p>
</div>
<div class="section" id="version-4-2-0">
<h2><a class="toc-backref" href="#id104">20.13 2006/02/16 - Version 4.2.0</a></h2>
<p>Removed <tt class="docutils literal"><span class="pre">BOM_UTF8</span></tt> from <tt class="docutils literal"><span class="pre">__all__</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">BOM</span></tt> attribute has become a boolean. (Defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.) It is
<em>only</em> <tt class="docutils literal"><span class="pre">True</span></tt> for the <tt class="docutils literal"><span class="pre">UTF16/UTF8</span></tt> encodings.</p>
<p>File like objects no longer need a <tt class="docutils literal"><span class="pre">seek</span></tt> attribute.</p>
<p>Full unicode support added. New options/attributes <tt class="docutils literal"><span class="pre">encoding</span></tt>,
<p>ConfigObj no longer keeps a reference to file like objects. Instead the
<tt class="docutils literal"><span class="pre">write</span></tt> method takes a file like object as an optional argument. (Which
will be used in preference of the <tt class="docutils literal"><span class="pre">filename</span></tt> attribute if that exists as
well.)</p>
<p>utf16 files decoded to unicode.</p>
<p>If <tt class="docutils literal"><span class="pre">BOM</span></tt> is <tt class="docutils literal"><span class="pre">True</span></tt>, but no encoding specified, then the utf8 BOM is
written out at the start of the file. (It will normally only be <tt class="docutils literal"><span class="pre">True</span></tt> if
the utf8 BOM was found when the file was read.)</p>
<p>Thanks to Aaron Bentley for help and testing on the unicode issues.</p>
<p>File paths are <em>not</em> converted to absolute paths, relative paths will
remain relative as the <tt class="docutils literal"><span class="pre">filename</span></tt> attribute.</p>
<p>Fixed bug where <tt class="docutils literal"><span class="pre">final_comment</span></tt> wasn't returned if <tt class="docutils literal"><span class="pre">write</span></tt> is returning
a list of lines.</p>
<p>Deprecated <tt class="docutils literal"><span class="pre">istrue</span></tt>, replaced it with <tt class="docutils literal"><span class="pre">as_bool</span></tt>.</p>
<p>Added <tt class="docutils literal"><span class="pre">as_int</span></tt> and <tt class="docutils literal"><span class="pre">as_float</span></tt>.</p>
</div>
<div class="section" id="version-4-1-0">
<h2><a class="toc-backref" href="#id105">20.14 2005/12/14 - Version 4.1.0</a></h2>
<p>Added <tt class="docutils literal"><span class="pre">merge</span></tt>, a recursive update.</p>
<p>Added <tt class="docutils literal"><span class="pre">preserve_errors</span></tt> to <tt class="docutils literal"><span class="pre">validate</span></tt> and the <tt class="docutils literal"><span class="pre">flatten_errors</span></tt>
example function.</p>
<p>Thanks to Matthew Brett for suggestions and helping me iron out bugs.</p>
<p>Fixed bug where a config file is <em>all</em> comment, the comment will now be
<tt class="docutils literal"><span class="pre">initial_comment</span></tt> rather than <tt class="docutils literal"><span class="pre">final_comment</span></tt>.</p>
<p>Validation no longer done on the 'DEFAULT' section (only in the root level).
This allows interpolation in configspecs.</p>
<p>Also use the new list syntax in <a class="reference internal" href="#validate">validate</a> 0.2.1. (For configspecs).</p>
</div>
<div class="section" id="version-4-0-2">
<h2><a class="toc-backref" href="#id106">20.15 2005/12/02 - Version 4.0.2</a></h2>
<p>Fixed bug in <tt class="docutils literal"><span class="pre">create_empty</span></tt>. Thanks to Paul Jimenez for the report.</p>
</div>
<div class="section" id="version-4-0-1">
<h2><a class="toc-backref" href="#id107">20.16 2005/11/05 - Version 4.0.1</a></h2>
<p>Fixed bug in <tt class="docutils literal"><span class="pre">Section.walk</span></tt> when transforming names as well as values.</p>
<p>Added the <tt class="docutils literal"><span class="pre">istrue</span></tt> method. (Fetches the boolean equivalent of a string
value).</p>
<p>Fixed <tt class="docutils literal"><span class="pre">list_values=False</span></tt> - they are now only quoted/unquoted if they
are multiline values.</p>
<p>List values are written as <tt class="docutils literal"><span class="pre">item,</span> <span class="pre">item</span></tt> rather than <tt class="docutils literal"><span class="pre">item,item</span></tt>.</p>
</div>
<div class="section" id="version-4-0-0">
<h2><a class="toc-backref" href="#id108">20.17 2005/10/17 - Version 4.0.0</a></h2>
<p><strong>ConfigObj 4.0.0 Final</strong></p>
<p>Fixed bug in <tt class="docutils literal"><span class="pre">setdefault</span></tt>. When creating a new section with setdefault the
reference returned would be to the dictionary passed in <em>not</em> to the new
section. Bug fixed and behaviour documented.</p>
<p>Obscure typo/bug fixed in <tt class="docutils literal"><span class="pre">write</span></tt>. Wouldn't have affected anyone though.</p>
</div>
<div class="section" id="version-4-0-0-beta-5">
<h2><a class="toc-backref" href="#id109">20.18 2005/09/09 - Version 4.0.0 beta 5</a></h2>
<p>Fixed bug in initialising ConfigObj from a ConfigObj.</p>
<p>Changed the mailing list address.</p>
</div>
<div class="section" id="version-4-0-0-beta-3">
<h2><a class="toc-backref" href="#id111">20.20 2005/08/28 - Version 4.0.0 beta 3</a></h2>
<p>Interpolation is switched off before writing out files.</p>
<p>Fixed bug in handling <tt class="docutils literal"><span class="pre">StringIO</span></tt> instances. (Thanks to report from
Gustavo Niemeyer.)</p>
<p>Moved the doctests from the <tt class="docutils literal"><span class="pre">__init__</span></tt> method to a separate function.
(For the sake of IDE calltips).</p>
</div>
<div class="section" id="version-4-0-0-beta-2">
<h2><a class="toc-backref" href="#id112">20.21 2005/08/25 - Version 4.0.0 beta 2</a></h2>
<p>Amendments to <em>validate.py</em>.</p>
<p>First public release.</p>
</div>
<div class="section" id="version-4-0-0-beta-1">
<h2><a class="toc-backref" href="#id113">20.22 2005/08/21 - Version 4.0.0 beta 1</a></h2>
<p>Reads nested subsections to any depth.</p>
<p>Multiline values.</p>
<p>Simplified options and methods.</p>
<p>New list syntax.</p>
<p>Faster, smaller, and better parser.</p>
<p>Validation greatly improved. Includes:</p>
<blockquote>
<ul class="simple">
<li>type conversion</li>
<li>default values</li>
<li>repeated sections</li>
</ul>
</blockquote>
<p>Improved error handling.</p>
<p>Plus lots of other improvements. <img src="/smilies/biggrin.gif" alt="Very Happy" height="15" width="15" /> </p>
</div>
<div class="section" id="version-3-0-0">
<h2><a class="toc-backref" href="#id114">20.23 2004/05/24 - Version 3.0.0</a></h2>
<p>Several incompatible changes: another major overhaul and change. (Lots of
improvements though).</p>
<p>Added support for standard config files with sections. This has an entirely
new interface: each section is a dictionary of values.</p>
<p>Changed the update method to be called writein: update clashes with a dict
method.</p>
<p>Made various attributes keyword arguments, added several.</p>
<p>Configspecs and orderlists have changed a great deal.</p>
<p>Removed support for adding dictionaries: use update instead.</p>
<p>Now subclasses a new class called caselessDict. This should add various
dictionary methods that could have caused errors before.</p>
<p>It also preserves the original casing of keywords when writing them back out.</p>
<p>Comments are also saved using a <tt class="docutils literal"><span class="pre">caselessDict</span></tt>.</p>
<p>Using a non-string key will now raise a <tt class="docutils literal"><span class="pre">TypeError</span></tt> rather than converting
the key.</p>
<p>Added an exceptions keyword for <em>much</em> better handling of errors.</p>
<p>Made <tt class="docutils literal"><span class="pre">creatempty=False</span></tt> the default.</p>
<p>Now checks indict <em>and</em> any keyword args. Keyword args take precedence over
indict.</p>
<p><tt class="docutils literal"><span class="pre">'</span> <span class="pre">',</span> <span class="pre">':',</span> <span class="pre">'=',</span> <span class="pre">','</span></tt> and <tt class="docutils literal"><span class="pre">'\t'</span></tt> are now all valid dividers where the
keyword is unquoted.</p>
<p>ConfigObj now does no type checking against configspec when you set items.</p>
<p>delete and add methods removed (they were unnecessary).</p>
<p>Docs rewritten to include all this gumph and more; actually ConfigObj is
<em>really</em> easy to use.</p>
<p>Support for stdout was removed.</p>
<p>A few new methods added.</p>
<p>Charmap is now incorporated into ConfigObj.</p>
</div>
<div class="section" id="version-2-0-0-beta">
<h2><a class="toc-backref" href="#id115">20.24 2004/03/14 - Version 2.0.0 beta</a></h2>
<p>Re-written it to subclass dict. My first forays into inheritance and operator
overloading.</p>
<p>The config object now behaves like a dictionary.</p>
<p>I've completely broken the interface, but I don't think anyone was really
using it anyway.</p>
<p>This new version is much more 'classy'. <img src="/smilies/wink.gif" alt="Wink" height="15" width="15" /> </p>
<p>It will also read straight from/to a filename and completely parse a config
file without you <em>having</em> to supply a config spec.</p>
<p>Uses listparse, so can handle nested list items as values.</p>
<p>No longer has getval and setval methods: use normal dictionary methods, or add
and delete.</p>
</div>
<div class="section" id="version-1-0-5">
<h2><a class="toc-backref" href="#id116">20.25 2004/01/29 - Version 1.0.5</a></h2>
<p>Version 1.0.5 has a couple of bugfixes as well as a couple of useful additions
over previous versions.</p>
<p>Since 1.0.0 the buildconfig function has been moved into this distribution,
and the methods reset, verify, getval and setval have been added.</p>
<tr><td class="label"><a class="fn-backref" href="#id7">[6]</a></td><td><p class="first">A side effect of this is that it enables you to copy a ConfigObj :</p>
<div class="pysrc"><span class="pycomment"># only copies members<br />
</span><span class="pycomment"># not attributes/comments<br />
</span><span class="pytext">config2</span> <span class="pyoperator">=</span> <span class="pytext">ConfigObj</span><span class="pyoperator">(</span><span class="pytext">config1</span><span class="pyoperator">)</span><span class="pytext"></span></div><p class="last">The order of values and sections will not be preserved, though.</p>
<tr><td class="label"><a class="fn-backref" href="#id9">[8]</a></td><td>The exception is if it detects a <tt class="docutils literal"><span class="pre">UTF16</span></tt> encoded file which it
<tr><td class="label"><a class="fn-backref" href="#id12">[11]</a></td><td>Passing <tt class="docutils literal"><span class="pre">(section,</span> <span class="pre">key)</span></tt> rather than <tt class="docutils literal"><span class="pre">(value,</span> <span class="pre">key)</span></tt> allows you to
change the value by setting <tt class="docutils literal"><span class="pre">section[key]</span> <span class="pre">=</span> <span class="pre">newval</span></tt>. It also gives you
access to the <em>rename</em> method of the section.</td></tr>
